\chapter{EXTENDING POINT}

\section{Introduction}

This section  describes \Point\  feature that allows
you to  access the functionality of \Point\ from any
program that  you write.  The idea is that you can
call another  program from  within \Point, and that
program can  then use  software interrupts to call
\Point\ and access its functions.

When \Point\  starts, it sets up an 8088 (or 8086 or
80286) software  interrupt (interrupt number 0x61,
but it  can be  changed in  \ff{pt.ini}) so  that  it
calls  an   interface  routine  in  \Point.    This
interface routine  uses the  parameters  that  are
passed in  the registers  to call various internal
functions in \Point.  These functions can do things
like:   get and set the selection, read characters
from the  files being  editing, insert  and delete
characters from  the files  being edited, open new
windows,  reposition   windows,  top   and  bottom
windows, scroll windows, display messages, execute
any \Point\ command, etc.

You can  essentially run  \Point\ by  remote control
from another  program using  software  interrupts.
This other  program can be written in any language
that has the ability to call software interrupts.

***(in the  next sentence)Do  you mean edilting in
\Point\ or  in some other way?  Does the program you
are running  have to  be started  from  the  \Point
editor  or   could  I,  for  example,  call  \Point
directly from  a word  processor?   I don't follow
this.***

\Point\ includes  commands that make it easy to call
the programs  you write  to extend \Point\ while you
are editing.

We will first describe the example extensions that
are included  in the  distribution.   Then we will
describe how  to set  up \ff{pt.ini}  to  call  these
extensions.     Finally  we   will  describe   the
interface routines  so that you can write your own
extensions to \Point.

\section{Distributed \Point\ extensions}

\subsection{Change case}

The program  ``pcase.exe'' will  change the  case of
the selection  in four different ways depending on
the argument it is given:

\begin{description}
	\item[1] $\Rightarrow$ Change all  letters in  the selection
	to upper case \\
	\item[2] $\Rightarrow$ Change all  letters in  the selection
	to lower case \\
	\item[3] $\Rightarrow$ Change the  case of  all letters
	in the selection \\
	\item[4] $\Rightarrow$ Make the  first letter  of each  word in
the selection  upper case  and make  all the other letters lower case
\end{description}

If no  argument is  passed, \Point\  will prompt the
user for the argument.

***The code  demonstrates?   (below)How do you get
to see it?***

The  code   ``pcase.c''  demonstrates  how  to  read
characters, how  to get and set the selection, how
to insert and delete characters, and how to get an
input  string   from  the  user  using  the  \Point
software interrupts.

\subsection{Run the \Point\ loop and support compiles}

The program  ``compile.exe'' contains  a  loop  that
runs  the   main   \Point\   loop   remotely   (from
``compile.exe'').   The ``compile.exe''  loop gets the
next  user  input  event  from  \Point,  determines
whether it  wants to  intercept the  command,  and
then either  passes the  input event back to \Point
for processing or handles the input event itself.

The  ``compile.exe''   program  supports   compiling
Microsoft C  programs from  within \Point\ (actually
from within  ``compile.exe'' running  \Point).    You
first compile  the C  program in  the top  window.
Then you  can step  through the compile errors one
at a time.

\section{Calling \Point\ extensions}

Fifty-six commands have been allocated for calling
programs that  make  use  of  the  \Point\  software
interrupt.   They are  commands 200  to 255.   Set
them up in the \ff{pt.ini} file as follows:

A character string can be assigned to any of these
56 commands.  The character string begins with the
command name.   You  can also (optionally) include
arguments to  the command  after the command name.
These arguments will be passed to the command when
it is  executed.  If the string ends with a space,
the user will be prompted for additional arguments
to the command.

Let us  look that  some examples of lines that you
might put in a \ff{pt.ini} (or ``ptlocal.ini'') file:

\begin{verbatim}
     c200="pcase" -- Example 1
     k061=200
     c201="pcase 1" -- Example 2
     [2
     "Menu Title"=-1
     "Make All Upper Case"=201
     $\cdots$
     ]
     c244="pgrep" -- Example 3
     m5=244
     c248="newprog arg1" -- Example 4
     k14=248
\end{verbatim}

Example 1  defines  command  200  to  execute  the
``pcase.com''  or   ``pcase.exe''  command   with   no
arguments.     \Point\  will  look  in  the  current
directory and then in the PATH directories to find
the file.   The  usual DOS  rule will be followed:
in each  directory \Point\ will look for ``pcase.com''
first, then  for ``pcase.exe'',  and then will go on
to the next directory if neither is found.

The second  line assigns  this command  to the  \key{F3}
(k061) key.   Thus when \key{F3} is pressed, the ``pcase''
command will be executed.

The second  example defines command 201 to execute
the  ``pcase''  command  with  argument  ``1''.    The
``pcase'' command  will be searched for as described
above.   On the  next line, user menu 2 is defined
to include an item that will execute this command.
Presumably this menu is attached as a drop down or
pop-up menu  in some  other place  in the \ff{pt.ini}
file.

The  third  example  defines  command  244  (these
command numbers  are arbitrary  -- as long as they
are in  the range  200  to  255)  as  the  ``pgrep''
command.   When invoked,  it will ask the user for
additional arguments, since the string ends with a
space.  This command (244) is then attached to the
South mouse  motion (m5=NNN)  of the  first  mouse
motion command.

The fourth  example assigns  command  248  to  the
program ``newprog''.  The first argument ``arg1'' will
be  used   automatically  and  the  user  will  be
prompted for  more arguments.  The command is then
attached to the \key{Ctrl-n} key (k14 or key 14).

\section{Overlay concepts}

The overlay  feature gives  you access  to some of
the internal  features and functions of \Point.  As
such you  should understand  some things about how
\Point\ is  implemented in  order to use the overlay
feature effectively.

\subsection{Virtual memory, pieces, and disk buffers}

\Point\ uses  a ``virtual  memory'' feature.  All file
characters are  kept in disk files, and buffers of
the most  recently used  blocks are  maintained in
\Point's memory.   The  ``buffers'' option allows you
to set the number of buffers \Point\ uses.  The more
buffers, the  less often  \Point\ has  to  read  and
write the  disk.  \Point\ also uses a data structure
called a  ``piece table'' to keep track of the edits
made in  a file.   That  is, \Point\  represents the
file as  a sequence of one or more ``pieces''.  Each
piece is  a span  of characters  from a disk file.
Combined with  the virtual  memory  feature,  this
means that  spans of file characters are contained
in \Point's disk buffers.

\subsection{Reading text characters}

***Later (in  5.4.3), you  call ``ax=1''  the  ``read
character'' function  and  ``ax=2''  the  ``get  span''
function.***

\Point\ includes  a function  that  reads  one  text
character from a file.  This function is available
as the  ``ax=1'' function  in the overlay interface.
When   \Point\    is   reading    file    characters
sequentially, it  uses a faster interface in which
it gets  the characters  directly  from  the  disk
buffer.   This function is available as the ``ax=2''
function in  the overlay  interface.  More care is
required when  using the ``ax=2'' function than when
using  the   ``ax=1''  function,  because  the  disk
buffers continually  change as different files are
accessed.   When you  get a  pointer into  a  disk
buffer,  ANY   other  \Point\  function  call  might
invalidate that buffer, and read data from another
area of  the disk  into it.   That  is, you cannot
make ANY  calls to other \Point\ functions while you
are using  a pointer from the ``ax=2'' function.  If
any other  functions intervene,  you must call the
``ax=2'' function  again.   Thus the ``ax=2'' function
is only  to be  used for  reading  a  sequence  of
characters.

\subsection{Handling windows}

There  are  several  windows  in  \Point\  that  are
special in  some way.   The ``active window'' is the
window to  which all  keyboard, top line, and menu
commands apply.   It  is marked on the screen by a
double lined  border.   The ``selection  window'' is
the window  that contains the selection.  Inserted
text always  goes in  front of  the selection  and
hence changes  the file  in the  selection window.
The ``top  window'' is  the window that is above, or
in front  of, all other windows, and fully visible
on the  screen.   No operations apply specifically
to it.

Many overlay functions apply to the active window.
For example,  the ``read character'' (ax=1) and ``get
span'' (ax=2)  functions get  characters  from  the
file  in  the  top  window;  the  ``scroll  window''
function (ax=4)  scrolls the  active window,  etc.
There is  also a  function (ax=5)  to  change  the
active window.

The ``insert  character''  (ax=8),  ``insert  string''
(ax=11), and  ``delete text''  (ax=8) functions  all
use the  selection, and hence apply to the file in
the selection  window, not  to  the  file  in  the
active window.

\subsection{The selection}

You can  get information  about the selection with
the ``get  selection information'' (ax=12) function.
With  the  ``set  selection  information''  function
(ax=13), some  selection information  can be  set.
Set  the   selection  itself   with  the   ``change
selection''   function   (ax=6).      The   ``insert
character''  (ax=8),   ``insert   string''   (ax=11),
``delete selection'' (ax=9), and ``search for string''
(ax=24) functions  all  change  the  selection  as
well.

\subsection{Changing windows}

\Point\ uses  the address  of window  structures  to
identify windows  internally.   It also uses these
addresses as  window identifiers  in  the  overlay
functions.    The  ``get  identifier  of  the  next
window'' (ax=22)  function is  used to look through
the windows.   You  pass  the  function  a  window
identifier, and  it passes  back the identifier of
the next  window.   If you  pass in a 0, it passes
back the identifier of the top window.  If you get
back a 0, then you passed in the identifier of the
bottom window.

The ``get  selection information''  function (ax=12)
will  give   you  the  window  identifier  of  the
selection   window,   and   the   ``set   selection
information''  function   (ax=13)  will   set   the
selection  window.     The   ``set  active  window''
function (ax=5) will change the active window.

Once you  have a  window identifier  you  can  get
information  about   it  with   the  ``get   window
location'' (ax=15)  and  ``get  window  information''
(ax=16) functions.

\subsection{Running the \Point\ loop from an overlay}

\Point's main  loop is very simple.  It looks for a
keyboard or  mouse event  and then  processes  it.
Overlay functions  allow  you  to  run  this  loop
remotely from  the overlay.    You  can  load  the
overlay once and leave it loaded while still using
\Point.   This saves  the overhead  of loading  the
overlay program  each time  you want to use one of
its functions.

The ``get  user input  event'' function (ax=26) gets
the next  input event.   You  can choose to handle
the event  yourself, or  you can  pass it  back to
\Point\ for  handling.   Do this  with  the  ``handle
input event'' function (ax=27).

Sometimes  you   will  want  \Point\  to  execute  a
function  for   which  there  is  not  an  overlay
interface  call.    The  ``execute  \Point\  command''
function (ax=25) will execute any \Point\ command.

\subsection{Text marks}

\Point\ has  a facility  for putting invisible marks
with  associated  (hidden)  text  into  the  file.
These  marks   and  their   associated  text   are
implemented with  zero length pieces.  This allows
you to  edit surrounding  text  extensively  while
text marks remain in place.  One use of text marks
is to  implement an  overlay that  compiles a file
and displays  the compiler error messages one at a
time.

***Note the  next paragraph  -- I  think ``inserted
string'' and  ``inserted text  mark'' in the original
addendum meant the same thing, and I shortened the
sentences accordingly.   But  please make sure I'm
correct here.***

Text marks  are inserted  into the  file with  the
``insert string''  function (ax=11).   The  inserted
string is  saved by  \Point\ but does not display in
the file  window, and  is not written out when the
file is saved.  To find a text mark, use the ``find
next text  mark'' function  (ax=28).  This function
starts looking  in the window, and at the place in
the window,  that you  specify.   It  returns  the
location of  the next text mark it finds, and also
returns the string of text that is associated with
that text  mark.  There is no limit on the size of
the text associated with a text mark.

\subsection{Menus}

***What is a place program?***

The ``show  menu'' function  (ax=30) allows  you  to
display menus  from an overlay.  \Point\ handles the
interaction and  menu selection,  and returns  the
value associated  with  the  menu  item  that  was
selected.   You must  pass this  function  a  menu
block that  contains ``far''  pointers  (offset  and
segment) to  the text  strings of  the menu items,
and an integer value for each menu item.  Thus the
place program must allocate space for all the menu
item strings  and build  the menu block before the
call.

\subsection{Cautions about using overlay functions}

The overlay  interface gives  you direct access to
some of  the internals  of \Point.   The  interface
tries to  check the  validity of the arguments you
give it,  but it  can be fooled.  It is quite easy
to crash \Point\ using these functions.  You must be
careful and  thoroughly test  your overlays, since
they can mess things up, lose text, etc., easily.

\section{Overlay interfaces}

Two  interfaces  to  the  software  interrupt  are
provided.  This section discusses a procedure call
interface  and  the  next  section  describes  the
software interrupt interface.

The file ``overlib.c'' provides the C bindings for a
procedure call  interface to  these functions.  If
you   use    these   functions   you   must   link
``overlib.obj'' with your program.

\subsection{Window and file management functions}

***Do ``int'' and ``char'' mean integer and character?
Also, at  the  end  of  ``fullName'',  is  that  ``+''
supposed to  be there?   Also, in ``getWInfo'', what
is ``long''?  And what is ``DS''?***

(int)w = findWindow(char *s, int fullName)
This function looks through all the windows
and finds one whose filename matches the
one in s
s is the filename to search for
fullName tells how to match strings.
fullName=1 means that the filename must
match the string name exactly.
fullName=0 means that only the basename
and file extension need to match the
string (s)+

(int)n = getNextWindow(int windowId, int
*nextWindowId)
windowId is the window to start from
nextWindowId is the window below it in the
stack of windows.  If windowId was 0,
then this is the windowId of the top
window
n is 1 if windowId was invalid and 0
otherwise

topBottomWindow(int how)
how tells how to top or bottom (see software
interrupt function 3)

redrawScreen()
The screen is redrawn.  This is used to show
changes that have been made since the
screen was last updated.  Most of these
functions do NOT automatically redraw
the screen after changes.

scrollWindow(int direction, int numberOfLines)
direction is 0 for up and 1 for down
numberOfLines is the number of lines to
scroll

(int)n = changeActiveWindow(int windowId)
windowId is the id of the new active window
n is 1 if the windowId was invalid and 0
otherwise

(int)n = getWLocation(int windowId, int *row1, int
*col1, int *row2, int *col2)
windowId is the window to get the location of
row1,col1 is the upper left corner of the
window
row2,col2 is the lower right corner of the
window
n is 1 if windowId was invalid and 0
otherwise

(int)n = getWInfo(int windowId, int nameOffset,
int nameSegment, int *topLine, int *bottomLine,
long *topPosition, long *bottomPosition)
windowId is the window to get information
about
nameOffset is the offset portion of the
address of a buffer where the name of
the file in the window will be copied

nameSegment is the segment portion of the
address of a buffer where the name of
the file in the window will be copied.
If this is 0, the procedure converts it
into the DS segment.
topLine is the line number of the top line
showing in the window
bottomLine is the line number of the first
line past the bottom line showing in the
window
topPosition is the character position of the
first character showing in the window
bottomPosition is the character position of
the first character beyond the last
character showing in the window

moveWindow(row1, col1, row2, col2)
row1,col1 is the new upper left corner of the
window
row2,col2 is the new lower right corner of
the window

(int)w = createWindow(nameOffset, nameSegment,
row1, col1, row2, col2)
nameOffset is the offset portion of the
string containing the name of the file
to load into the new window
nameSegment is the segment portion of the
string containing the name of the file
to load into the new window.  If this is
0, the procedure converts it into the DS
segment.
row1,col1 is the upper left corner of the new
window
row2,col2 is the lower right corner of the
new window
w is the window Identifier of the newly
created window

closeWindow(how)
how tells how to close the window (see
software interrupt function 20)

***What is the ``target window''?***

saveFile()
The file in the target window is saved.

\subsection{Text handling functions}

selectText(long selBegin, long selEnd, int
options)
selBegin is the logical character position of
the first character in the selection
selEnd is the logical character position of
the last character in the selection
options is 0 for select only; 1 for select
and show the selection in the window; 2
for select and delete the selected
characters

getSelectionInfo(int *selMode, int *selWindow,
long *selBegin, long *selEnd)
selMode returns the selection mode
selWindow returns the windowId of the window
containing the selection
selBegin is the logical byte position in the
file of the first byte of the selection
selEnd is the logical byte position in the
file of the last byte of the selection

(int)n = setSelectionInfo(int windowId, int
selMode)
windowId is the id of the new selection
window
selMode is the new selection mode
n is 1 if the windowId was invalid and is 0
otherwise

insertString(int length, int stringOffset, int
stringSegment, hidden)
This call serves two separate functions.  The
first is to provide a faster and easier
way to insert a string of characters
into a \Point\ file.  It is used in place
of a sequence of ``insertCharacter''
calls.  For this purpose use hidden=0.
The second function of this call is to
insert ``text marks'' into the file.  A
text mark is a hidden marker in the
text.  It has a string associated with
it but the string does not appear in the
displayed file and will not be written
out if the file is saved.  Function
``getNextTextMark'' is used to find text
marks and retrieve the text string
associated with them.  Function
``deleteTextMarks'' will remove all
existing text marks.  Saving a file will
also delete all existing text marks in
the file.
length is the number of bytes to insert
stringOffset is the offset part of the
address of the string to insert.
stringSegment is the segment part of the
address of the string to insert.  If
this is 0, the procedure converts it
into the DS segment.
hidden indicates whether this is a text mark
or not.  Use hidden=0 to insert a text
string into the file.  Use hidden=1 to
insert a hidden text mark into the file.

insertCharacter(char ch)
ch is inserted in front of the selection

deleteSelection()
The selected characters are deleted.

(long)nextLinePos = readLine(long startPos, char
*line)
This function reads a line from the file in
the active window.
startPos is the character position of the
first character to read in the line.
line is the buffer the string read will be
placed in.  The line will be read to the
next newline and the newline will be
part of the returned string.
nextLinePos is the character position after
the line just read.

(char)ch = readOneChar(long charPosition)
charPosition is the logical character
position in the file of the character to
read
ch is the character at that position.  ch = 0
if charPosition is less than 0 or equal
to or greater than the size of the file

(int)eof = getSpan(long charPosition, long
*firstByte, long *lastByte)
charPosition is the logical character
position in the file of the character to
read
firstByte is a FAR pointer to the buffer
position where character(charPosition)
is
lastByte is a FAR pointer to the last buffer
position after firstByte that contains
valid characters from the file.
eof is 1 when charPosition is at (or beyond)
the end of the file.

(int)ch = readChar(long charPosition)
This call uses function ``getSpan'' to read
acharacter more quickly than
``readOneChar'' will.  This call uses a
cache that will be rendered invalid by
ANY other interface calls (other than
``readChar'').  If you make any other
calls and then call ``readChar'' again you
may get incorrect characters unless you
call ``invalidateReadCache'' before
calling ``readChar'' again.
charPosition is the logical character
position in the file of the character to
read
ch is the character read.  If ch = -1, then
charPosition was at (or beyond) the end
of the file.

invalidateReadCache()
This call invalidates the cache used in the
above function ``readChar''.

\subsection{Positioning functions}

gotoLineNumber(lineNumber)
lineNumber is the line to move to.  The
window is repositioned so that this line
is the top line in the window.

(long)n = lineNumberToOffset(int lineNumber)
lineNumber is the line number in the file (in
the active window) for which you want
the character offset
n is the character position in the file (in
the active window) of the first
character of line ``lineNumber''

(long)n = searchForString(unsigned int
stringOffset, unsigned int stringSegment)
This call searches in the selection window,
starting at the current selection, for
the string passed.
stringOffset is the offset part of the
address of the string to search for
stringSegment is the segment part of the
address of the string to search for.  If
this is 0, the the data segment of the
program (DS) will be used
***(next sentence)  This doesn't make sense to me.
Does the ``of'' go with ``position''?***

n is the character position in the file of
the first character of the string being
searched for.  This will be -1L if the
string was not found in the selection
window between the selection and the end
of the file.

\subsection{User input and display output functions}

getInput(int promptOffset, int promptSegment, int
defaultOffset, int defaultSegment, int oneChar)
promptOffset is the offset part of the
address of the string that will prompt
the user
promptSegment is the segment part of the
address of the string that will prompt
the user.  If this is 0, the procedure
converts it into the DS segment.
defaultOffset is the offset part of the
address of the string that will be the
default response

defaultSegment is the segment part of the
address of the string that will be the
default response.  If this is 0, the
procedure converts it into the DS
segment.
oneChar is 1 if a single character response
is required.  Otherwise the user must
terminate the response with the \key{Enter}
key.

displayMessage(int messageType, int msgOffset, int
msgSegment)
messageType indicates how the message is
displayed (see software interrupt
function 10)
msgOffset is the offset part of the address
of the string to display.
msgSegment is the segment part of the address
of the string to display.  If this is 0,
the procedure converts it into the DS
segment.

(int) value = showMenu(unsigned int offset,
unsigned in segment, int row, int col)
This function displays a menu and allows the
user to select an item from the menu.
offset,segment is the far address of the menu
block (see overlay.h for the format of a
menu block).
row,col is the screen position of the upper
left corner of the menu.
value is the value associated with the menu
item chosen by the user.

\subsection{BIOS functions}

checkOverlay(int vector)
Checks to see if 8086 interrupt vector
``vector'' has been initialized.

vector is the interrupt vector number.  The
default value is 0x61.

scrollUp(int row1, int col1, int row2, int col2,
int nLines, int attr)
Calls the BIOS scroll up function.
row1,col1 is the upper left corner of the
scroll region
row2,col2 is the lower right corner of the
scroll region
nLines is the number of lines to scroll
attr is the character attribute of the blanks
that are put into the empty character
positions.

clearScreen()
Uses ``scrollUp'' to clear the screen.

setCPos(int row, int col)
Moves the cursor to the specified row and
column.
row,col is the position to move the cursor
to.

\subsection{Event and command functions}

(int)eventType = getInputEvent(int *arg1, int
*arg2, int *arg3, int *arg4, int *arg5)
This command gets the next user input event
and returns a description of it.
EventType is the type of event:
eventType=1 is a keyboard event.  In this
case the ASCII character will be
returned in arg1 and the IBM PC keyboard
scan code will be returned in arg2.

eventType=2 is a mouse event.  In this case:
arg1 is the mouse event mask, arg2 is
the mouse button state, arg3 is the
vertical mouse position, arg4 is the
horizontal mouse position, and arg5 is
\Point's internal mouse event identifier
for this event.  The mouse event
identifier must be passed back to \Point
if you want \Point\ to handle the mouse
event.

handleInputEvent(int eventType, int arg1, int
arg2)
eventType is the eventType from the
``getInputEvent'' call.  If eventType=1,
arg1 is the ASCII character and arg2 is
the scan code.  This call can also be
used to feed any keystrokes into \Point
and have them acted upon.  It is not
necessary to have gotten the keyboard
event from ``getInputEvent''.  If
eventType=2, arg1 is the mouse event
identifier gotten from ``getInputEvent''.

pointCommand(int commandNumber, unsigned int
windowId)
commandNumber is the \Point\ command number
(see the \Point\ reference manual for a
list of command numbers) of a command to
be executed
windowId is the windowId of the window on
which you want the command to act

\subsection{Text mark functions}

(long)n = getNextFileMark(unsigned int w, long
startPosition, unsigned int stringOffset, unsigned
int stringSegment)
This call finds text marks with hidden text
that have been inserted with the
``insertString'' call with hidden=1.  It
looks in the window w starting at
character position startPos.
w is the window to search in
startPos is the character position to start
searching from
stringOffset is the offset part of the
address of a string to copy the hidden
text into when the file mark is found
stringSegment is the segment part of the
address to copy the hidden text to.  If
it is 0, the current data segment (DS)
will be used.
***next sentence?***

n is the character position in the file (in
the window w) of the character position
the text mark was found at.

deleteFileMarks(unsigned int w)
This call removes from the file in window w
all the file marks that have been
inserted with calls to ``insertString''
with hidden=1.

\section{Software interrupt interface}

\subsection{The overlay vector}

This  section  specifies  the  software  interrupt
interface.   \Point\ uses software interrupt 0x61 as
default.   This can  be changed  with  a  line  in
\ff{pt.ini} setting  the ``overlayVector'' option.  For
example, to use interrupt 0x67 = 103 (decimal) put
the following line in your \ff{pt.ini}:

\begin{verbatim}
     overlayVector=103
\end{verbatim}

\subsection{Notational conventions}

Often long  integers and  far points are passed to
these calls and passed back by these calls.  Since
the 8086  registers are  only 16  bits long,  such
quantities are  put in pairs of registers:  either
cx,dx or  si,di.   The first  register (cx  or si)
always contains  the low order 16 bits of the long
or the offset part of the far address.  The second
register (dx or di) always holds the high order 16
bits of  the long  or the  segment part of the far
address.   We will  label the  32 bit  quantity as
either a ``long'' or a ``far''.

\subsection{The software interrupt calls}

ax=1 -- Read Character From the Active Window
Inputs:
cx,dx (long) = logical byte number
Outputs:
ax = character read (0 if byte number is
out of range)
Function: This call reads the logical byte
indicated from the file in the target
window and returns it.

ax=2 -- Get Span of Characters From the Active
Window
Inputs:
cx,dx (long) = logical byte number

Outputs:
ax = 1 => EOF; 0 => not EOF
cx,dx (far) = first byte of the span
si,di (far) = last byte of the span
Function: \Point\ keeps the file characters in
sequences of varying length (depending
on what editing has taken place) in
memory buffers.  This call gets a
pointer to the designated character and
all characters following it in the
buffer.  This call also gets a span from
the target window.  If the file has not
been edited at all, you will get a
pointer to 1024 characters.  It is
faster to use this call than call ax=1,
since one call ax=2  gets you a pointer
to a number of characters.
Warning: These pointers are only valid until
you make ANY other call on \Point.  If
you make another call, assume that these
pointers are no longer valid.

ax=3 -- Top or Bottom the Active Window
Inputs:
bx = 0 => top window
1 => top/bottom window
2 => bottom window
3 => swap the two top windows
Outputs:
None
Function: The active window is changed to be
the top or bottom window (or the two top
windows are interchanged).

ax=4 -- Scroll the Active Window
Inputs:
bx = 0 => scroll up
1 => scroll down
cx = number of lines to scroll

Outputs:
None
Function: The active window is scrolled up or
down by the designated number of lines.

ax=5 -- Change the Active Window
Inputs:
bx = window identifier of the new target
window
Outputs:
ax = 0 => command completed normally;  1
=> invalid window identifier
Function: Changes the the active window

ax=6 -- Change Selection
Inputs:
bx = 0 => only select the text
1 => select the text and scroll the
window so that the text shows in the
window
2 => select and delete the
designated text (the new selection will
be the first character after the deleted
characters.
cx,dx (long) = logical byte number of
the first byte of the selection
si,di (long) = logical byte number of
the last byte of the selection
Outputs:
None
Function: This command sets the selection.

ax=7 -- Redraw the Screen
Inputs:
None
Outputs:
None

Function: The screen is redrawn.  \Point\ will
not update the screen in many cases when
you call these functions.  It is up to
you to ask for the screen to be updated.
This will save time by avoiding a screen
update when you do not need the screen
updated.

ax=8 -- Insert Character (in front of the
selection)
Inputs:
bx = character to insert
Outputs:
None
Function: The character is inserted into the
file just in front of the selection.
The new selection is the first character
of the old selection.

ax=9 -- Delete the Selected Characters
Inputs:
None
Outputs:
None
Function: the selected characters are
deleted.  The new selection is the first
character after the deleted characters.

ax=10 -- Display Message On Message Line
Inputs:
bx = 0 => erase sticky message
1=> normal message
2 => message in the prompt color
3 => message in the error color (and
wait for character to be typed)
4 => sticky message
5 => message on the line above the
message line.
cx,dx (far) = address of the message
string
Outputs:
None
Function: A message is displayed to the user.
Normal messages (types 1, 2 and 3) are
erased when the next user command is
issued or when the screen is redrawn.
Sticky messages (type 4) stay until they
are explicitly erased.  Normal messages
come in the normal, prompt and error
colors.  An error message always waits
for the user to acknowledge it with a
keystroke.  Type 5 allows you to write a
message line on the line just above the
bottom line of the screen.  This is
useful for writing instructions and then
requesting user input (with function
14).

ax=11 -- Insert Character String or Text Mark
Inputs:
bx = number of characters in the string
cx,dx (far) = address of the string
si = 0 => insert string
1 => insert text mark and hidden
string
Outputs:
None
Function: If si=0, the designated character
string is inserted in front of the
selection.  The new selection is the
first character of the old selection.
If si=1, then a text mark is inserted
into the file and the string passed as
associated with the text mark is
inserted as hidden text.

ax=12 -- Get Selection Information
Inputs:
None
Outputs:
ax = selection mode
0 => character mode
1 => word mode
2 => line mode.
bx = selection window identifier
cx,dx (long) = first byte of the
selection
si,di (long) = last byte of the
selection
Function: This function gets information
about the selection.

ax=13 -- Set Selection Information
Inputs:
bx = input window identifier
cx = new selection mode (must be 0, 1,
or 2)
Outputs:
ax = 0 => command completed normally
1 => windowId was invalid
(selection window was not changed)
2 => selection mode was out of
range (selection mode was not changed).
Function: This function changes the selection
window and the selection mode.  It will
probably always be followed by a call to
change the selection itself (function
ax=6) since the selection limits in the
old window are unlikely to be the
correct ones for the new window.

ax=14 -- Get User Input
Inputs:
bx = 0 => get a string terminated by
\key{Enter}
1 => get a single character (no
\key{Enter} required)
cx,dx (far) = prompt string
si,di (far) = default reply string
Outputs:
The string entered is copied into the
prompt string (overwriting the prompt).
The maximum length of the prompt,
default, and reply strings is 80
characters
Function: The prompt string is displayed on
the bottom line of the display.  The
default reply string is entered as a
suggested reply.  Then the user can
enter new input or accept the suggested
input.

ax=15 -- Get Window Location
Inputs:
bx = window identifier
Outputs:
ax = the row of the upper border of the
window
bx = the column of the left border of
the window
cx = the row of the lower border of the
window
dx = the column of the right border of
the window
si = 0 => command completed normally
1 => invalid window identifier

Function: This command gets the location on
the screen of any window.

ax=16 -- Get Window Information
Inputs:
bx = window identifier
cx,dx (far) = address of the string for
file name
Outputs:
The filename of the file in the window
is copied into the string whose address
was passed in (dx,cx)
ax = the line number of the top line in
the window
bx = the line number of the bottom line
in the window
cx,dx (long) = the position of the first
character showing in the window
si,di (long) = position of the first
character beyond the last character in
the window

Function: This command gets information about
any window.

ax=17 -- Goto Line Number
Inputs:
bx = line number to go to
Outputs:
None
Function: The active window is scrolled so
that the designated line number is the
top line in the window.

ax=18 -- Move the Active Window
Inputs:
cx = the row of the new upper border of
the window
dx = the column of the new left border
of the window
si = the row of the new lower border of
the window
di = the column of the new right border
of the window
Outputs:
None.
Function: The active window is moved to the
designated screen position.

ax=19 -- Create New Window
Inputs:
cl = the row of the upper border of the
new window
ch = the column of the left border of
the new window
dl = the row of the lower border of the
new window
dh = the column of the right border of
the new window
si,di (far) = address of a string
containing the filename of the file to
load into the new window
Outputs:
ax = 0 => window create completed
normally
1 => window create failed.
bx = window identifier of the newly
created window
Function: A new window is created at the
specified location with the specified
file name.  The new window becomes the
active window.

ax=20 -- Close the Active Window
Inputs:
bx = 0 => save the file in the window if
it has been changed
1 => ask the user whether to save
the file in the window if it has been
changed
2 => do not save the file in the
window even if it has been changed.
Outputs:
None
Function: The active window is closed.

ax=21 -- Save File in the Active Window
Inputs:
None
Outputs:
None
Function: This call will save the file in the
active window.

ax=22 -- Get Identifier of the Next Window
Inputs:
bx = input window identifier
Outputs:
ax = 0 => function completed normally
1 => input window identifier was
invalid.
bx = window identifier of the next
window below the input window identifier
(in bx when the function is called) in
the stack of windows;  if the input
window identifier was 0, then the window
identifier of the top window is
returned;  if the output window
identifier is 0 then the input window
identifier was the bottom window.

Function: This function provides a way to
look through the list of all open
windows by scanning through from top to
bottom.  You start by sending in a 0 and
getting the window identifier of the top
window.  Then call this function to get
each window in turn, until a 0 is
returned.

ax=23 -- Convert a Line Number to a Character
Position
Inputs:
bx = line number
Outputs:
cx,dx (long) = the low order 16 bits of
the character position of the first
character of the requested line number.
Function: This function provides a way to
convert from a line number to a
character offset.  Line numbers are used
by language processors and other
programs, but most of these \Point
interface functions use character
positions.

ax=24 -- Search for String
Inputs:
bl = value of ignoreCase for this search
bh = value of searchMode for this search
cx,dx (long) = offset part of the
address of the search string
Outputs:
cx,dx (long) = the character position at
which the string was found.  If the
string was not found these will both be
-1

Function: This function gives you access to
\Point's fast search command.  It is much
quicker than getting the text and
searching it yourself, mainly because of
the overhead of getting the text.

ax=25 -- Execute a \Point\ command
Inputs:
bx = window identifier
cx = command number
Outputs:
ax = 0 => function completed normally
1 => input window identifier was
invalid.
Function: This function allows you to execute
any \Point\ command.  The windowId is only
used for those commands that take a
window argument.

ax=26 -- Get User Input Event
Inputs:
None.
Outputs:
bx = event type
1 => keyboard event
2 => mouse event
cx = ASCII character (keyboard event)
cx = mouse event mask (mouse event)
dx = IBM PC keyboard scan code (keyboard
event)
dx = mouse button state (mouse event)
si = vertical mouse coordinate (mouse
event)
di = horizontal mouse coordinate (mouse
event)
ax =  mouse event identifier (mouse
event)

Function: This function (along with the next
one) allows you to run the main \Point
loop from an overlay program.  This
method would be used for programs that
you want to load as overlays and keep
loaded.  They are essentially extensions
to \Point.  Because it is  not required
to load the overlay to each time, the
response will be faster.  There are two
kinds of events.

ax=27 -- Handle Input Event
Inputs:
bx = event type (from function 26)
cx = ASCII character (event type = 1)
cx = mouse event identifier (event type
= 2)
dx = keyboard scan code (event type = 1)
Outputs:
None.
Function: This function provides a means to
pass input events back to \Point\ so it
can handle them.

ax=28 -- Find Next File Mark
Inputs:
bx = input window identifier
cx,dx (far) = address of the output
string
si, di = position from which to start
looking
Outputs:
cx,dx (long) = character position of the
text mark that was found (-1L if none
found)

Function: This function searches in window w,
starting at the start position, for a
text mark (inserted using function 11).
The location of the text mark is
returned (-1L if none is found) and the
(hidden) string associated with that
text mark is placed in the output
string.

ax=29 -- Delete All Text Marks In a Window
Inputs:
bx = input window identifier
Outputs:
None.
Function: This function removes all the
(hidden) text markers from the file in
window w.

ax=30 -- User Menu Selection
Inputs:
cx = row of upper left corner of the
menu
dx = column of upper left corner of the
menu
si,di (far) = address of menu block
Outputs:
bx = number of the menu item selected.
Function: This function displays a menu and
lets the user select an item from the
menu.  The menu is positioned with its
upper left corner at row cx and column
dx.  The address of a menu block is
passed.  This menu block defines the
strings in the menu and the return
values associated with each one.  The
file ``overlay.h'' contains a C structure
definition of a menu block.

***The rest of this chapter is on the hard (paper)
copy of  pt200 but not in the file.  I'm typing it
in, but  I don't  know if  you  want  it  here  or
not.***

ax=31 -- Reserved

ax=32 -- Overlay suspend
Inputs:
None
Outputs:
cx,dx (far)  = address  of a string that
will contain  ``0'' if  the overlay should
exit.
Function: This function is used to suspend an
overlay.   When an  overlay is  finished
but wants  to remain  loaded,  it  makes
this call.   \Point\ returns to its normal
processing.   When the overlay is called
again, \Point\  will  notice  that  it  is
already loaded,  and  return  from  this
function.  The overlay can then continue
without the  overhead of  having to load
again.   In addition,  the overlay  will
retain all  of  its  state  information.
This call  is an  alternative to running
the main loop from the overlay.
Primary  and  secondary  overlays:  For  more
support of  overlays,  we  have  made  a
distinction    between    primary    and
secondary overlays.  The primary overlay
is loaded  and remains  loaded  for  the
duration of  the editing  session.   The
secondary   overlays    are    transient
overlays  that   are  loaded  after  the
primary overlay.  If the overlay name is
followed by  a ``*'',  it is  marked as  a
primary overlay.    Otherwise  it  is  a
secondary overlay.

